/*	
   ______   ______    
  /\__  __\/\ \___\ 
  \/_/\ \_/\ \ \__/    __   __     __       
     \ \ \  \ \ \__\  /\ \ /\ \  /'__`\  
     _\_\ \  \ \ \_/_ \ \ \\_\ \/\  __/       
    /\____/   \ \_____\\ \_____/\ \____\   
    \_/__/     \/_____/ \/____/  \/____/                   
 
 	This file is part of the JEVE core API.

    JEve is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 3 of the License, or
    (at your option) any later version.

    JEve is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
    
    Copyright 2008 JEve Project (JEveProject@gmail.com)
 */
package be.fomp.jeve.core.api;

import be.fomp.jeve.core.exceptions.JEveConnectionException;
import be.fomp.jeve.core.exceptions.JEveParseException;
import org.jdom.Document;

/**
 * <pre>
 *  ______   ______
 * /\__  __\/\ \___\
 * \/_/\ \_/\ \ \__/    __   __     __
 *    \ \ \  \ \ \__\  /\ \ /\ \  /'__`\
 *    _\_\ \  \ \ \_/_ \ \ \\_\ \/\  __/
 *   /\____/   \ \_____\\ \_____/\ \____\
 *   \_/__/     \/_____/ \/____/  \/____/
 * </pre>
 * This file is part of the JEVE core API.<br />
 * <br />
 * <p/>
 * Interface containing the accessor methods for the EVE-Online API
 * which require the limited access API key.
 *
 * @author Sven Meys
 */
public interface LimitedAPI extends StandardAPI {

	/*--[ API V1 ]--*/

	/**
	 * This method retrieves the characters on the given account
	 * from http://api.eve-online.com/account/Characters.xml.aspx.
	 *
	 * @param userID The user ID
	 * @param apiKey The API key
	 * @return A list of characters
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getCharacters(int userID, String apiKey) throws JEveConnectionException, JEveParseException;

	/**
	 * This method retrieves the character sheet of the corresponding character ID
	 * from http://api.eve-online.com/char/CharacterSheet.xml.aspx.
	 *
	 * @param userID	  The user ID
	 * @param apiKey	  The API key
	 * @param characterID The Character ID
	 * @return A character sheet
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getCharacterSheet(int userID, String apiKey, int characterID) throws JEveConnectionException, JEveParseException;

	/**
	 * This method retrieves the skill which your character is currently training
	 * from http://api.eve-online.com/char/SkillInTraining.xml.aspx.
	 *
	 * @param userID	  The user ID
	 * @param apiKey	  The API key
	 * @param characterID The character ID
	 * @return A corporation sheet
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getSkillInTraining(int userID, String apiKey, int characterID) throws JEveConnectionException, JEveParseException;

	/*--[ API V2 ]--*/

	/**
	 * This method retrieves the corporation sheet
	 * from http://api.eve-online.com/corp/CorporationSheet.xml.aspx.
	 *
	 * @param userID The user ID
	 * @param apiKey The API key
	 * @return A corporation sheet
	 * @throws JEveConnectionException If connecting to the web API failed
	 * @throws JEveParseException	  If parsing to a document failed
	 */
	Document getCorporationSheet(int userID, String apiKey, int characterID) throws JEveConnectionException, JEveParseException;

	/*--[ API V3 ]--*/

}
